Dink table reference

In DinkLua, just about every DinkC-equivalent engine feature is stored in the "dink" table, with everything else that isn't instead listed somewhere in the object reference. I didn't want to write this but too many people nagged. As of v0.94 of YeOldeDink, many features have been moved to the global objects described in the separate object reference, and most mathematical equivalents are available built into Lua as described in the relevant section below.



Inventory

Functions that deal with the inventory.

dink.add_item(string script, int seq, int frame) adds an item to the inventory with script of script, and sequence of seq and frame of frame to display to the player.

dink.add_magic(string script, int seq, int frame) as above, except adds it to one of the 8 magic slots instead.

dink.kill_this_item(string script) removes the item with the corresponding script from the inventory by running drop(). Will run holdingdrop() and disarm() if currently in use, and then redraw the status bar.

dink.kill_this_magic(string script) as above, except for magic.

dink.free_items() returns the amount of free item slots remaining in the normal inventory.

dink.free_magic() as above, but for magic instead.

dink.kill_cur_item() runs disarm(), holdingdrop(), and drop() of the currently-equipped item and halts the script.

dink.kill_cur_magic() same as above except for magic.

dink.arm_weapon() runs disarm() then arm() of the currently-equipped weapon.

dink.arm_magic() the same as above for magic.

dink.count_item(string script) returns the amount of items in the inventory that have the script "script".

dink.count_magic(string script) same for magic.

dink.get_item(string script) returns the inventory slot number of the item with the specified script

dink.get_magic(string script) as above for magic.

Status bar and interface

dink.show_inventory() will cause the inventory to be displayed.

dink.set_keep_mouse(bool) determines if the mouse cursor should still be active when game mode is changed to 3 (on).

dink.draw_status() re-draws the status bar.

dink.stop_entire_game() halts everything while a choice menu is active. Does not halt script timers and whatnot. Mainly used for the level up choice menu.

dink.set_mode(int mode) sets the game mode, which may be 0, 1, 2, or 3. Mode zero is when the engine is initted or restarted, after which mode 1 is automatically applied (mouse mode). Mode 3 is main mode with status bar and such.

Audio and Multimedia

Background music, sound effects, and video.

dink.playavi(string movie) will play movie with path relative to dmoddir if ffmpeg's ffplay is installed and available.

dink.playmidi(string music_file, int fadein) plays music_file (relative to SOUND in dmoddir) with an optional fade-in time in milliseconds, assuming the filetype is supported. More musical features are listed in the object reference.

dink.playsound(int sound_number, int min_speed, int rand_speed_to_add, sprite, bool repeat_p) plays sound effect in slot "sound_number". Please see the guide and object reference for more information. Everything apart from sound_number is optional.

dink.load_sound(string wav_file, int slot) attempts to load wav_file (path relative to dmoddir's SOUND) into the specified slot, of which there are 200.

dink.kill_all_sounds() only halts sounds set looping with "survive".

dink.stopmidi() stops the currently-playing background music.

dink.turn_midi_off() switches off background music playback entirely.

dink.turn_midi_on() switches it back on.

dink.loopmidi(bool loop_midi) determines if background music will loop indefinitely or not.

dink.set_music_vol(int volume) sets the currently-playing music's volume, which may be between zero and 128.

Text

Fonts and displayed text. Sprite text is covered in the object reference.

dink.initfont(string fontname) replaces the text TTF with fontname. In YeOldeDink, the font will be searched for in system fonts, or in Fontconfig, or in the root of dmoddir. This may be operating system-dependent.

dink.set_font_color(int index, int r, int g, int b) sets specified text colour index (1 to 15) with the corresponding RGB values between 0 and 255.

dink.say_xy(string text, int x, int y) displays text at the specified co-ordinates, with an x offset of 300 or so. Also returns a sprite object.

dink.say_stop_xy(string text, int x, int y) as above but interrupts the script until dismissed or some time has passed.

Scripting and utility

Things that relate to scripts, or that provide access to engine features that may not be visible to the player.

dink.set_callback_random(string func, int min, int max) - runs function "func" after a random interval between min and max +min in milliseconds. Also returns a callback index that may later be murdered manually.

dink.wait(int delayms) pauses the execution of the script for at least the amount specified by delayms in milliseconds, after which it is resumed. May overshoot by a little bit or a lot.

dink.script_attach(int sprite) assigns the current script a different owner sprite. Common values are zero (the screen), and 1000 (persistent across screens) when not a living sprite.

dink.callback_kill(int slot) nullifies the specified callback slot for a script set to wait and resumes its execution.

dink.spawn(string script) activates an instance of script "script" which may also be in DinkC assuming the backend is enabled.

dink.kill_this_task() halts the currently-executing script.

dink.get_cheat() returns a bool indicating if the user has opened the inbuilt cheat window.

dink.restart_game() kills off all sprites, halts all repeating sounds and scripts, sets mode and screenlock to zero (runs "start" script), resets the save data, hitmap, and button input, runs "main" script, and resets all DinkC variables.

dink.debug(string message) writes message to the debug log, accessible from the debug menu in YeOldeDink, as well as to debug.txt in dmoddir if started with debug mode on (-d flag), also visible on the command line on certain platforms.

dink.get_version() returns 108.

dink.get_client_fork() returns 3 in YeOldeDink.

dink.get_fps() returns the amount of frames per second.

dink.get_platform() returns zero on Windows, 2 on macOS, 3 on GNU/Linux, and -1 otherwise.

dink.get_last_sprite() returns the number of the most recently created sprite, for checking how many sprites there are. Does not return a sprite object.

dink.kill_game() Exits the program.

dink.scripts_used() returns the amount of script slots being used.

dink.var_used() returns how many DinkC variables are in use at the time of invocation.

dink.get_truecolor() returns a bool indicating if the user launched with 24-bit graphics mode enabled.

Loading and Saving

Saved games and serialisation etc.

dink.save_game(int slot) makes a standard save in the specified save slot.

dink.load_game(int slot) attempts to load the game from the specified slot.

dink.set_save_game_info(string info) overwrites the line in saves with info.

dink.reset_timer() resets the amount of minutes indicated in savefiles back to zero.

dink.todisk(variable, string filename) will serialise a table or other variable to the specified filename in the root of dmoddir.

dink.fromdisk(string filename) returns your variable from the file. Should return nil if it doesn't exist but might not...

dink.clear_editor_info() clears all editor sprite overrides such as barrels and burnt trees while resetting their timers.

dink.copy_to_clipboard(string clipboard_info) will copy a string to the clipboard, such as a high score, or debug information.

dink.game_exist(int slot) returns a bool indicating if the save slot exists or not.

Graphical

Frames, sequences, BMPs, and more.

dink.show_bmp(string bmp_name, bool show_position) displays bmp_name with an optional flashing thingy indicating which screen you're on as per show_marker. Path for BMP is from root of dmoddir. Should also show PNGs in YeOldeDink.

dink.copy_bmp_to_screen(string bmp_name) blits bmp_name onto the background layer containing the tiles and background sprites. Can also be a PNG or something.

dink.draw_screen() redraws the screen. returns true if successful.

dink.draw_background() re-draws the background layer with the tiles, and clear off any blood etc.

dink.init(string iniline) parses a dink.ini line.

dink.preload_seq(int sequence) loads the specified sequence into RAM so it is displayed faster.

dink.fade_down() fades down the screen over a period of 1 second or thereabouts, and pauses the script until completed. White pixels are still visible.

dink.fade_up() fades up the screen if faded down.

dink.fill_screen(int palette_index) fills the background layer with the corresponding palette index (0-255).

dink.load_palette(string bmp_file) updates the palette according to bmp_file. Path is relative to root of dmoddir. Also usable in 24-bit mode.

Buttons and input

dink.wait_for_button() waits for a button press. Might not do anything at the moment.

dink.stop_wait_for_button() stops the above.

dink.activate_bow() activates the bow, sets the player sprite's pseq to 100 + direction.

dink.push_active(bool can_push) determines if the player sprite may push against something.

dink.set_button(int button, int function) doesn't do anything in YeOldeDink. Joystick settings are set from the menus.

Sprites

dink.disable_all_sprites() sets the "disabled" property of all living sprites to true.

dink.enable_all_sprites() does the opposite to above. Sets them to false.

dink.create_sprite(int x, int y, int brain, int sequence, int frame) creates a sprites with the specified parameters and returns a sprite object. More details are in the object reference.

dink.get_sprite_with_this_brain(int brain, int sprite_ignore) sprite_ignore may be a sprite object. Returns the first sprite object that has the specified brain.

dink.get_rand_sprite_with_this_brain(int brain, int sprite_ignore) same as above except picks randomly.

dink.set_dink_base_push(int base_sequence) sets the push sequence for the player sprite. More easily set by using player.base_push.

dink.set_smooth_follow(int smooth) determines if sprites will follow another using all 8 directions and a different algorithm. Set to 1 to switch on. Should really be changed to a bool at some point. Off by default, which uses the old <=1.07 algo.

dink.get_next_sprite_with_this_brain(int brain, int sprite_ignore, int starting_sprite) Loops over all sprites starting with starting_sprite, and finds the next one with the specified brain while ignoring a specified sprite if not set nil.

Screen, collision data, and tiles

dink.draw_hard_map() redraws the screen's collision data, and updates editor sprites with their override information.

dink.load_screen(int screen) loads a screen in map.dat according to its dink.dat index value. Also updates the screen timer, and the show_bmp indicator flasher.

dink.inside_box(int x, int y, int left, int right, int top, int bottom) returns a bool indicating if the specified X/Y co-ordinates are within the box specified by left, right, top and bottom.

dink.map_hard_tile(int tile_position, int hard_tile_index) updates one of the 96 alt_hard tiles with one of the 800 tiles in hard.dat.

dink.map_tile(int tile_position, int tile_index) updates one of the 96 screen tiles with one of the 7808 tilescreen tiles.

dink.load_tile(string tilescreen, int tilescreen_index) overwrites one of the 61 tilescreen indices with another tilescreen BMP or PNG. Path starts in TILES in dmoddir. The first 41 will be saved in the save file.

dink.load_map(string mapdat, string dinkdat) replaces the current map file with the specified filenames. Path is relative to root of dmoddir.

Numbers, date, and time

A whole bunch of mathematical functions are included in Lua's inbuilt math library that replace many DinkC features such as "math_abs". The Lua Manual contains a full list of them.

dink.get_time_real() returns an integer indicating the current time quantified in minutes. Lua also contains time-related features built in.

dink.get_time_game() returns the amount of minutes of the user's current session as stored in the save file after being added to the difference between the start time and the current time. The start time is reset upon saving or something.

dink.get_date_year(), get_date_month, get_date_day return an integer containing year, month, or day of month.

dink.random(int range, int base) return a random number between base, and base + range -1.

It is preferable to use Lua's math.random() for something more intuitive. math.random(3) will return 1, 2, or 3. math.random(5, 6) will return either 5 or 6.

Other/weird

dink.force_vision() doesn't do anything and never will.

dink.get_burn() returns 1

dink.get_last_bow_power() returns the power of the last bow shot, which is the amount of time in milliseconds it was activated.

dink.stopcd() displays a funny message.